When Ediff starts up, it displays a small control window, which accepts the Ediff commands, and two or three windows displaying the files to be compared or merged. The control window can be in its own small frame or it can be part of a bigger frame that displays other buffers. In any case, it is important that the control window be active (i.e., be the one receiving the keystrokes) when you use Ediff. You can switch to other Emacs buffers at will and even edit the files currently being compared with Ediff and then switch back to Ediff at any time by activating the appropriate Emacs windows.
Ediff can be invoked interactively using the following functions, which can be run either from the minibuffer or from the menu bar. In the menu bar, all Ediff's entry points belong to three submenus of the Tools menu: Compare, Merge, and Apply Patch.
ediff-filesediffediff-backupediff-current-filerevert-buffer.ediff-buffersediff-files3ediff3ediff-buffers3edirsediff-directoriesedirs3ediff-directories3edir-revisionsediff-directory-revisionsedir-merge-revisionsediff-merge-directory-revisionsedir-merge-revisions-with-ancestorediff-merge-directory-revisions-with-ancestorediff-windows-wordwiseediff-windows-linewiseediff-regions-wordwiseediff-regions-linewiseediff-windows-linewise, but compares the regions
line-by-line. See ediff-windows-linewise for more
details.ediff-revisionediff-patch-fileepatchSince the patch might be in a buffer or a file, you will be asked which is the case. To avoid this extra prompt, you can invoke this command with a prefix argument. With an odd prefix argument, Ediff assumes the patch is in a file; with an even argument, a buffer is assumed.
Note that ediff-patch-file will actually use
the patch utility to change the original files
on disk. This is not that dangerous, since you will always
have the original contents of the file saved in another file
that has the extension .orig. Furthermore, if the file is under
version control, then you can always back out to one of the
previous versions (see the section on Version Control in the
Emacs manual).
ediff-patch-file is careful about versions
control: if the file to be patched is checked in, then Ediff
will offer to check it out, because failing to do so may
result in the loss of the changes when the file is checked
out the next time.
If you don't intend to modify the file via the patch and
just want to see what the patch is all about (and decide
later), then ediff-patch-buffer might be a
better choice.
ediff-patch-bufferepatch-bufferThis function would refuse to apply a multifile patch to a
buffer. Use ediff-patch-file for that (and when
you want the original file to be modified by the
patch utility).
Since the patch might be in a buffer or a file, you will
be asked which is the case. To avoid this extra prompt, you
can invoke this command with a prefix argument. With an odd
prefix argument, Ediff assumes the patch is in a file; with
an even argument, a buffer is assumed.
ediff-merge-filesediff-mergeediff-merge-files-with-ancestorediff-merge-with-ancestorediff-merge, but with a third ancestor
file.ediff-merge-buffersediff-merge-buffers-with-ancestoredirs-mergeediff-merge-directoriesedirs-merge-with-ancestorediff-merge-directories-with-ancestorediff-merge-revisionsediff-merge-revisions-with-ancestorediff-documentationediff-show-registryeregistryIf you want Ediff to be loaded from the very beginning of your Emacs session, you should put this line in your ~/.emacs file:
(require 'ediff)
Otherwise, Ediff will be loaded automatically when you use one of the above functions, either directly or through the menus.
When the above functions are invoked, the user is prompted for
all the necessary information—typically the files or
buffers to compare, merge, or patch. Ediff tries to be smart
about these prompts. For instance, in comparing/merging files, it
will offer the visible buffers as defaults. In prompting for
files, if the user enters a directory, the previously input file
name will be appended to that directory. In addition, if the
variable ediff-use-last-dir is not nil,
Ediff will offer previously entered directories as defaults
(which will be maintained separately for each type of file, A, B,
or C).
All the above functions use the POSIX diff or
diff3 programs to find differences between two
files. They process the diff output and display it
in a convenient form. At present, Ediff understands only the
plain output from diff. Options such as ‘-c’ are not supported, nor is the
format produced by incompatible file comparison programs such as
the VMS version of diff.
The functions ediff-files,
ediff-buffers, ediff-files3,
ediff-buffers3 first display the coarse, line-based
difference regions, as reported by the diff program.
The total number of difference regions and the current difference
number are always displayed in the mode line of the control
window.
Since diff may report fairly large chunks of text
as being different, even though the difference may be localized
to just a few words or even to the white space or line breaks,
Ediff further refines the regions to indicate which
exact words differ. If the only difference is in the white space
and line breaks, Ediff says so.
On a color display, fine differences are highlighted with color; on a monochrome display, they are underlined. See Highlighting Difference Regions, for information on how to customize this.
The commands ediff-windows-wordwise,
ediff-windows-linewise,
ediff-regions-wordwise and
ediff-regions-linewise do comparison on parts of
existing Emacs buffers. The commands
ediff-windows-wordwise and
ediff-regions-wordwise are intended for relatively
small segments of buffers (e.g., up to 100 lines, depending on
the speed of your machine), as they perform comparison on the
basis of words rather than lines. (Word-wise comparison of large
chunks of text can be slow.)
To compare large regions, use
ediff-regions-linewise. This command displays
differences much like ediff-files and
ediff-buffers.
The functions ediff-patch-file and
ediff-patch-buffer apply a patch to a file or a
buffer and then run Ediff on the appropriate files/buffers,
displaying the difference regions.
The entry points ediff-directories,
ediff-merge-directories, etc., provide a convenient
interface for comparing and merging files in different
directories. The user is presented with Dired-like interface from
which one can run a group of related Ediff sessions.
For files under version control, ediff-revision
lets you compare the file visited by the current buffer to one of
its checked-in versions. You can also compare two checked-in
versions of the visited file. Moreover, the functions
ediff-directory-revisions,
ediff-merge-directory-revisions, etc., let you run a
group of related Ediff sessions by taking a directory and
comparing (or merging) versions of files in that directory.